Use of this package requires a $35 shareware fee. This fee entitles one developer to use this package in an unlimited number of applications and to distribute those applications without limit.
However, you may distribute it only as part of a complete 4D application. You may not resell it by itself, or as part of any kind of shell or toolkit without the author's express written permission. You may not remove or alter any portion of this notice or the comments.
If you decide to use it, please make shareware work and pay the fee. Also please provide me with some address so that I can contact you regarding any upgrades.
Scott Ribe
CIS 73507,3041
604 Inverness Cliffs
Birmingham, AL 35242
INSTALLATION:
==============
You may use 4D External Mover to install this package. However, I have included the resources necessary to make the commands group into two popups in the procedure editor, and as far as I know no version of External Mover prior to External Mover Plus 1.0.2 will move these correctly. If you want the popups and you don't have External Mover Plus 1.0.2 or later, first install with 4D External Mover, then open your Proc.ext or structure with ResEdit, find the 4DPX name "PictBundle", note its number, and make sure the THM# and FON# resources have the same ID as the 4DPX.
CHANGES
========
Version 1.1 adds support for pointer arrays, the GetBdlItemType function. It also adapts to an unannounced change in the way 4D presents version information to externals.
Version 1.1.1 corrects a bug introduced in 1.1 that would cause memory corruption when putting a 2D array into a bundle.
This update is free to all who have paid their shareware fee.
PURPOSE:
==========
First off, obviously, PictBundle is like an enhanced version of the old Array2Picture utilities. PictBundle will work with most 4D data types, all array types, and lets you stuff multiple items into one picture. So you can use it to stuff arrays into a picture field of a record, which is how it got its start in life.
Some of the extensions, however, were inspired by 4D version 3 and multiple processes.
Process-to-process communications in 4D are complicated by the fact that you can only pass arguments between processes by setting up batches of interprocess variables. This is clumsy at best, and can get really awful if you want to have multiple instances of the same process active at once, or allow multiple calls to a process to queue up. What's really needed is a language facility like C structs or Pascal records that allow data to be grouped into compound types.
PictBundle provides enough grouping capability to solve those PPC problems, and to provide a mechanism where 4D procedures can be called with variable argument lists and return multiple values of variable type. If you've ever needed to implement a dispatch mechanism that would "pass through" any type of data, you can do it with this package.
PictBundle is intended to mimic in 4D some of the functionality of C structs or Pascal records, in fact I originally called it “PictStruct” instead of “PictBundle”. I changed it because it doesn't quite implement structures.
It does:
° allow you to bundle up any number of data items into one logical and physical unit;
° check typing of read/write operations on the bundle’s elements for consistency.
It does not:
° allow you to name the elements contained in a bundle;
° allow you to write to the values in an arbitrary sequence;
° enforce typing of bundles themselves.
USES:
=====
Pass sets of parameters between processes without creating a whole mess of interprocess variables.
Post sets of parameters into a queue, where the queue is simply an array of pictures rather than bunches of different arrays.
Pass variable sets parameters into a dispatch procedure that just passes them on through without looking at them.
Return variable sets parameters from a dispatch procedure depending on what function was actually called.
Implement variable call/return syntax for certain procedures.
For MSI Access: Bundle up a record's values or a bunch of related data into a single global variable for use with SetBundle or GetBundle. Cleaner than using bunches of global variables. Faster than converting a record into an array of text. Easier than specifying a whole bunch of different bundle arrays.
OVERVIEW:
===========
The mental model of how these externals are to be used is something like a box. You take an empty box and toss a bunch of stuff into it. Then you carry it around as long as you want, put on a shelf in the basement, mail it to a friend, or whatever. Eventually, somebody somewhere dumps the contents out of the box and uses them.
I would describe the set of externals implemented as complete but primitive. If you want to arrange your box neatly or decorate it, you get to code your own gewgaws.
A bundle is a flat block of data consisting of a 14-byte header followed by the data that you have put into it. It works rather like a disk file, in that it has a current read/write position and a logical and physical size.
Writing to it copies the passed value into the bundle at the current read/write position, advances the read/write position, and sets the logical end at the value just written (in other words, unlike a disk file, a write always truncates it to the current position). As more room is needed, the data block is grown in integral multiples of an allocation unit (default is 32 bytes).
Reading from it grabs the value at the current position and advances the read/write position. An attempt to read beyond the logical end of the bundle posts an EOF (-39) error. An attempt to read a value that is not the same type as the one at the current position posts a type mismatch error (59). Reads are non-destructive so you can back up and reread the same data as many times as you like. If a type mismatch error occurs, the read does not advance the read/write position, so you cannot keep on reading past an error.
Any attempt to access a bundle created with an incompatible version of this package posts a version mismatch error (54). This is version 1.1. Any bundles created with 1.0 can be read by it, but its bundles cannot be read by 1.0.
QUICK START:
==============
Basically you create a bundle:
C_PICTURE(myBdl1)
myBdl1:=CreateBundle
Add data to it:
PutBdlLong(myBdl1;$num)
PutBdlString(myBdl1;vCompName)
PutBdlText(myBdl1;[Contacts]comments)
PutBdlArray(myBdl1;as30Phones)
Reset the read/write mark:
SetBdlPos(myBdl1;0)
Pass it to another procedure, store it into a field, write it to disk, whatever. Then read the data back:
$num:=GetBdlLong(myBdl1)
vCompName:=GetBdlString(myBdl1)
[Contacts]comments:=GetBdlText(myBdl1)
GetBdlArray(myBdl1;as30Phones)
Of course, when writing to the bundle you should check for errors after each write to make sure that you haven't run out memory.
PASSING ARGUMENTS:
===================
The values being copied into a bundle, that is the values being passed as the second argument to PutBdlXXX, can be anything: globals, locals, interprocess, constants, fields, or array elements. Values that will be modified must be passed as global variables; including both the Bundle picture variables themselves in nearly all calls, and the arrays in GetBdlArray calls.
4D generally only allows externals to modify the value of global variables. So any value that is going to be modified should be a global variable. In 3.0, this includes interprocess and process variables.
In particular, this means that your picture variables used to store bundles should be simple global variables (process or interprocess), not elements of an array, not fields, and not local variables.
SetBdlPos(myBdl;0) or (◊myBdl;0) will work.
Neither SetBdlPos([file1]bundle;0) nor SetBdlPos(myBdls{1};0) will work. And StBdlPos($myBdl;0) is not supposed to work. (See discussion below.)
NOTE THAT GETTING A VALUE FROM A BUNDLE MODIFIES IT BY ADVANCING THE READ/WRITE POSITION. This means that you must use global variables even when getting values back out of a bundle. If for instance you call GetBdlLong([file1]bundle) you may get a value, but the next attempt to read from [file1]bundle will yield incorrect results.
Of course, you can assign a bundle into an array or local variable when you are done using it, and assign it back to a global before using it again. In practice, you could get away with only one global picture variable and always use assignment to and from local picture variables or picture arrays. (Just remember that assigning a picture copies its contents, so you don't want to shuffle around big pictures too much.)
My testing indicates that it actually works with bundles stored in local picture variables. But the Externals Kit states "You may pass fields or local variables, however, a changed value can not be returned to them." I don't know whether this is an obsolete restriction that was lifted in some version of 4D, or whether passing locals to a procedure that modifies them will cause trouble. Although I've not seen any problems, I'd suggest following the documented restrictions, unless you feel really brave.
Likewise, in 4D 3.0 even GetBdlArray(myBdl;$LocalArray) seems to work, but I wouldn't trust it without exhaustive testing.
REFERENCE:
===========
BundlePackErr -> long
------------------
Returns any error posted by the last call into this package. Mostly Mac memory manager errors. No error is 0. Read past the end of the bundles is EOF (-39). A type mismatch error is 59. A version mismatch error is 54.
Under 3.0 returns only the error posted by the last call into this package from the same process.
CreateBundle -> picture
-----------------
Creates and returns a bundle with a properly initialized header and no data. (14 bytes of header and 18 bytes of preallocated data space.) MUST be called before using the other commands in this package.
Passing some picture value not created this way can cause disastrous results.
ClearBundle(picture)
--------------
Clears the bundle to a properly initialized header and no data. Releases all but the minimum 18 bytes of data space. SHOULD NEVER be called with a picture of any type other than one created by CreateBundle.
If you are looking for maximum speed and repeatedly building a bundle that is large or has many elements, don't clear it between uses. Just SetBdlPos(aBdl;0) so that the memory will not be released, and when you write to it again it won't need to be resized.
Of course, the converse is true. If you've written a large amount of data into a bundle and expect to reuse it with only a small amount of data, you should ClearBundle(aBdl) to release the memory.
CopyBundle(picture) -> picture
Gotcha! There is no such command provided in the package. Just use:
aBdl2:=aBdl1
See, this is why it's good to read the documentation!
GetBdlVersion(picture) -> long
--------------------
Returns the version of these externals used to create this bundle. The version is carried with the bundle in case I have to change the data format in a future release. Version 1.0 returns a 1; version 1.1 returns a 2.
CompareBdls(picture;picture) -> long
---------------------
Returns 1 if the two bundles are byte for byte identical, 0 otherwise.
This can be used on any picture value, including those created as a real picture or those created by other externals. But any difference at all, including just a time stamp or unique id buried in a comment, will cause the two to be considered not equal. So before using this on a non-bundle pict, you'd better have an understanding of the structure in the pict.
SetBdlBlockSize(picture;long)
--------------------
Bundles, like disk files, are allocated in integral blocks in an attempt to avoid constantly resizing the data handle and grossly fragmenting memory when adding small variables. This sets the allocation size for the bundle. The default is 32 bytes.
SetBdlPos(picture;long)
--------------
Sets the read/write position. Note that a write ALWAYS truncates the bundle at the end of the written data.
Most commonly used to reset the mark to begin reading after writing:
SetBdlPos(aBdl;0)
Note that bundles maintain their read/write position when saved to a file, etc. So after writing you must always reset the mark before reading.
GetBdlPos(picture) -> long
----------------
Returns the current read/write position of the bundle.
GetBdlLogLen(picture) -> long
-------------------
Returns the current logical length of the bundle, that is the length of the data that has actually been written into the bundle.
To append to a bundle after backing up and reading, you can:
SetBdlPos(aBdl;GetBdlLogLen(aBdl))
GetBdlPhyLen(picture) -> long
-------------------
Returns the physical size of the handle. Is equal to the logical size plus the size of the header information plus any fraction of an allocation block that has not been used.
This just returns the handle size, and so can be used on any picture value created by any external.
GetBdlItemType(picture) -> long
Returns the type of the item at the current read/write position. If the position is at the end of the array returns 5 (undefined) and posts an EOF error.
PutBdlShort(picture;short)
---------------
Writes the short integer value into the bundle at the current read/write position.
GetBdlShort(picture) -> short
------------------
Returns the short integer value from the bundle's current read/write position.
PutBdlLong(picture;long)
---------------
Writes the long integer value into the bundle at the current read/write position.
GetBdlLong(picture) -> long
-----------------
Returns the long integer value from the bundle's current read/write position.
PutBdlReal(picture;real)
---------------
Writes the real value into the bundle at the current read/write position.
GetBdlReal(picture) -> real
-----------------
Returns the real value from the bundle's current read/write position.
PutBdlDate(picture;date)
---------------
Writes the date value into the bundle at the current read/write position.
GetBdlDate(picture) -> date
-----------------
Returns the date value from the bundle's current read/write position.
PutBdlString(picture;string)
-----------------
Writes the string value into the bundle at the current read/write position.
GetBdlString(picture) -> string
-------------------
Returns the string value from the bundle's current read/write position.
PutBdlText(picture;text)
---------------
Writes the text value into the bundle at the current read/write position.
GetBdlText(picture) -> text
-----------------
Returns the text value from the bundle's current read/write position.
PutBdlPict(picture;picture)
---------------
Writes the pict value into the bundle at the current read/write position.
Note that since bundles are just picts, this command lets you nest bundles inside each other.
GetBdlPict(picture) -> picture
-----------------
Returns the pict value from the bundle's current read/write position.
PutBdlArray(picture;array)
----------------
Writes the array (and the index of its currently selected element) into the bundle at the current read/write position.
This works for all array types, 1 or 2 dimension, any size up to the limit of available memory. As of version 1.1 it works for pointer arrays as well, but see the warning below.
Note also that 4D's conventions regarding 2D arrays is followed strictly. A column of a 2D array is itself precisely an array of the base type. So:
ARRAY TEXT(myArray;5;10)
PutBdlArray(myBdl;myArray{5})
is perfectly legal.
Both the type and ordinality of the array are considered part of the value's type for error checking when reading the array back. For string arrays the string size is considered part of the type as well, but a size mismatch does not generate an error.
GetBdlArray(picture;array)
----------------
Reads the array (and the index of its currently selected element) from the bundle's current read/write position.
This works for all array types, 1 or 2 dimension, any size up to the limit of available memory. The procedure will redimension the array as needed. As of version 1.1 it works for pointer arrays as well, but see the warning below.
Note also that 4D's conventions regarding 2D arrays is followed strictly. A column of a 2D array is itself precisely an array of the base type. So:
ARRAY TEXT(myArray;5;10)
GetBdlArray(myBdl;myArray{5})
is perfectly legal.
Both the type and ordinality of the array are considered part of the value's type for error checking when reading the array back.
If you write from a string array and then read back into a string array whose elements are of a different size, no error will be posted. Instead the strings in the bundle will be properly read into the new array: truncated (for a shorter destination) or left-aligned (for a longer destination). The read operation will be much faster if the original source and destination arrays have elements of the same size, because I can just use a single BlockMove instead of handling each string separately.
If there is not enough memory available to build the new array, the existing array will be destroyed before that is discovered. The procedure will in that case create a 0-dimensioned array with 1 null element and return it, so that 4D will not crash on a subsequent access to the array. (Of course the error will be available via BundlePackErr as always.)
The format and contents of pointers is not documented by ACI. Pointers cannot be passed to or returned from externals. It just so happens that 4D uses a standard format for all arrays, and will allow an array of pointers to be passed to an external. So I can simply grab the data and copy it.
However, since the meaning of the data is not defined, I cannot guarantee all aspects of the semantics of passing pointers through bundles.
An array of pointers to process variables unpacked in the same process in which it was packed will result in the pointers pointing the same instances of the variables. If unpacked in a different process, they will point to the instances of those variables in the process in which they are unpacked. (Just like passing a pointer via an interprocess variable.)
What happens if you unpack a pointer array in a different instance of the application? In other words if you send it across the network to another workstation, or save it to file or disk and retrieve it later after the user has quit and restart the program? I have no idea; I don't intend to find out; and I suggest strongly that you don't try to do this.
To all you out there who know what you're doing, please don't take offense at the tone of the comments for the following three commands. This stuff really is for knowledgeable C programmers and I just wanted to very strongly discourage folks from getting in over their heads...
PutBdlHandle(picture;long)
-----------------
Assumes that the long integer passed is actually a handle created by some other external package, takes the data in that handle and copies it into the bundle, typed as a PICT.
These commands:
PutBdlHandle(myBdl;myHdl1)
SetBdlPos(myBdl;0)
myHdl2:=GetBdlHandle(myBdl)
cause myHdl2 to be a handle to a copy of the data in myHdl1.
You can follow PutBdlHandle with GetBdlPict, or PutBdlPict with GetBdlHandle, and no error will be generated, the position will be advanced, everything will be OK, and you can keep reading. I just can't think of a reason WHY you'd want to do that, and don't know what the heck you'd do with the resulting data??
You should know EXACTLY what you are doing and what the structure of the data in your handle is before calling this procedure. Note in particular that if the handle contains other handles or pointers, then of course only the handles or pointers, not the data they reference, will be copied. Therefore if you use this to copy a handle that is subsequently disposed by its creator, your copy will contain invalid references, and using it will probably crash your system. (Yep, it can be really ugly when one half of a pair of Siamese twin handles dies...)
DON'T ASK ME FOR HELP WITH THE THREE HANDLE-ORIENTED COMMANDS. I AM NOT A SUBSTITUTE FOR INSIDE MACINTOSH.
GetBdlHandle(picture) -> long
-------------------
Requires that the next item to be read from the bundle is of type PICT, allocates a handle for the data, copies the data into it, and returns the handle.
The pict data could have been put into the bundle using either PutBdlPict or PutBdlHandle. (But only PutBdlHandle really makes sense.)
If a4dLong contains a handle then:
a4dLong := GetBdlHandle(myBundle)
Does NOT dispose the handle currently in a4dLong, you just lose track of it. Once again, you should know what you're doing before you start messing around with handles.
DisposBdlHandle(long)
---------------
If you have to ask what this does, you should not ever consider calling it under any circumstances!
Source code is (roughly, after factoring out my macros for accessing and casting 4D package arguments):
DisposHandle (*(Handle *)(PackArgs[1]));
If you don't understand that, go back and reread the preceding warnings about messing with the handle commands.
TECHIE STUFF:
=============
If you're a C programmer and you know how to write 4D externals and you wish to write your own externals to work with my bundles, here's what you need to know:
typedef struct
{ struct
{ long pBlock, pEnd, pPos;
char bVersion, bOptions;
} header;
char pData;
} PictStruct;
/*
pEnd length of actual data, may be shorter than pict size
(like a file's logical size as opposed to physical)
pPos 0-based offset of next byte to be read or written
pBlock allocation unit to use when growing the data handle
pData first character of data
bVersion version of the externals that created this bundle
bOptions 8 bits for bundle options, currently there are none
*/
Just follow these two rules and you should be able to "share" bundles with me:
1) You should read/write your own data types in precisely matched pairs. Don't try to read data that I write, and don't try to write data for me to read.
2) Make sure to maintain pEnd and pPos consistently.
